%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% none
%
%==========================================================================

%==========================================================================
% The function "setWaitbar" create a structure of waitbar settings
% referring to the same waitbar but appropriate for use in different
% calling functions.
% INPUT: "waitbarHandle" specifies a handle to an existing waitbar window
% which is to be set.
% "partitionLenArr" is an optional vector specifying the length of the
% waitbar portion to be reserved for each of the different settings.
% Typically these length would reflect processing time.
% "totalsArr" is an optional vector specifying a total for each of the
% different settings. Typically, this will reflect the number of same-kind
% objects being processed which not necessarily correlates well with 
% processing time.
% OUTPUT: "waitbarStructArr" returns a column vector of structures. Each
% entry holds one particular setting consisting of the waitbar handle,
% a starting position on the waitbar as a number between 0 and 1, a
% relative length along the waitbar as a number between 0 and 1 (those
% numbers need to add up to 1), an initial value for a counter that counts
% the events whose progress is being illustrated by the waitbar, and a
% total reflecting the total number of events of the said kind.
%==========================================================================
function waitbarStructArr = setWaitbar(waitbarHandle, partitionLenArr, totalsArr)

if (nargin < 1)
    return;
end
if ( (nargin < 2)||(isempty(partitionLenArr)) )
    partitionLenArr = 1;
end
if (nargin < 3)
    totalsArr = [];
end

% Compute the relative lengths of the intervals in the waitbar partition.
% They add up to 1.
relativeLenArr = (partitionLenArr')./sum(partitionLenArr);

% Arrange as a column vector for convenience.
totalsArr = totalsArr';

% If the array of totals contains less entries than the number of partition
% intervals, then fill in with empty arrays. Otherwise, take exactly as
% many of its entries as needed.
numIntervals = numel(relativeLenArr);
if (numel(totalsArr) < numIntervals)
    tempCellArr = cell(numIntervals - numel(totalsArr), 1);
    totalsCellArr = [num2cell(totalsArr); tempCellArr];
else
    totalsCellArr = num2cell(totalsArr(1:numIntervals));
end

% Set structure of waitbar settings.
waitbarStructArr = struct('handle', waitbarHandle, ...
    'index', num2cell((1:numIntervals)'), ...
    'totalIndices', num2cell(numIntervals(ones(numIntervals, 1))), ...
    'start', num2cell(cumsum([0; relativeLenArr(1:(end - 1))])), ...
    'length', num2cell(relativeLenArr), ...
    'first', num2cell(ones(size(relativeLenArr))), ...
    'total', totalsCellArr);

return;
% end of the function "setWaitbar"
